Release 10.1A: OpenEdge Development:
Programming Interfaces

Accessing the control handle

Once the ActiveX control is instantiated, the control-frame affords access to one widget and three COM objects, including the:

Control-frame widget.
Control container (the control-frame COM object).
Control collection (a standard COM object).
ActiveX control (the target COM object).

Figure 16–4 shows the chain of handle references that connect a control-frame widget (with widget handle CF) to an ActiveX control (with the Name CSSpin).

Figure 16–4: Handle references to access ActiveX controls

The chCF reference is a component handle to the control-frame COM object (control container) and the chCOL reference is a component handle to the control collection. Thus in the 4GL, you can instantiate and get the handle to an ActiveX control in two ways:

Using the name of the ActiveX control (CSSpin) as if it were a property (Control-Name property) of the control container (chCF:CSSpin).
Using the indexed Item property of the control collection (chCOL:Item(1)).

Once you have the component handle of the ActiveX control, you can access all of its properties and methods. (The chCSSpin reference is a component handle variable you might set from chCF:CSSpin or chCOL:Item(1).) The following examples reference a reduction of typical code generated by the AppBuilder. For a closer look at actual code generated by the AppBuilder, see the "Programming ActiveX controls in the AppBuilder" section.

Using the Control-Name property of the control container

This example show how you might access the component handle to the CSSpin control using the Control-Name property:

DEFINE VARIABLE chCSSpin AS COM-HANDLE. /* ActiveX Control */ DEFINE VARIABLE CtrlFrame AS WIDGET-HANDLE. /* Control-Frame Widget */ DEFINE VARIABLE chCtrlFrame AS COM-HANDLE. /* Control-Frame COM Object */ DEFINE VARIABLE OCXFile AS CHARACTER /* .wrx file pathname */ /* ... Define a FRAME widget named ’Foo’ ... */ /* Create OCX Container */ CREATE CONTROL-FRAME CtrlFrame ASSIGN / FRAME = FRAME Foo:HANDLE. CtrlFrame:NAME = "CtrlFrame":U. /* Load (instantiate) ActiveX control */ OCXFile = SEARCH ( "csspinapp.wrx":U ). chCtrlFrame = CtrlFrame:COM-HANDLE. chCtrlFrame:LoadControls( OCXFile, "CtrlFrame":U ). chCSSpin = chCtrlFrame:CSSpin /* Control handle via the Control Name */

The bolded code is the code you might add to appropriate sections of your application; the rest is a simplified version of code the AppBuilder might generate. Note how the AppBuilder uses the control-frame name (CtrlFrame) to generate handle variable names and to locate the control instance in the csspinapp.wrx file. The actual control name (CSSpin) is the OCX name specified for the control at design time (in this case, the CSSpin default).

Using the item property of the control collection

This similar example uses the control collection to return the control’s component handle:

DEFINE VARIABLE chCSSpin AS COM-HANDLE. /* ActiveX Control */ /* ... The AppBuilder-generated code from the previous example ... */ chCSSpin = chCtrlFrame:Controls:Item(1). /* Control handle via Item( ) */

The handle connections

The previous examples rely on attributes, properties, and methods supported by Progress to get a component handle from a control-frame widget handle (see Figure 16–4). Thus, to provide access to the control-frame widget and its related COM objects:

The control-frame widget has a COM-HANDLE attribute that returns the component handle of the control-frame COM object.
The control-frame COM object has a Controls property that returns the component handle of the control collection. You can then use the Item property on the collection component handle to get the component handle of the control.
Note: The control collection is a standard COM object that is used to access sets of like objects (objects in the same class).
The control-frame COM object has a special property named after the ActiveX control that returns the component handle of the control.
The control-frame COM object provides a Widget-Handle property that returns the widget handle of the instantiating control-frame widget.